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I. 
Introduction 


C-ISAM is a library of C-language functions 
which create and manipulate indexed file systems. 
Once the C-ISAM library has been linked with a user 
program it will be able to perform all the tasks 
necessary for the maintenance and manipulation of a 
user defined indexed file system. 
These tasks in- 
clude the creation of indexed file systems 
(isbuild), the addition (isaddindex) and deletion 
(isdelindex) of indexes, the addition (iswrite, 
iswrcurr), deletion (isdelete, isdelcurr), and 
modification (isrewrite, isrewcurr) of data records 
, the renaming (isrename) and erasing (iserase) of 
indexed file systems, random and sequencial access 
of records (isread, isstart) within an indexed file 
system, and finally the locking of individual 
records (isread, isrelease), or whole file systems 
(islock, isunlock)-- all in a multi-user environ- 
ment. 


C-ISAM is both flexible and efficient. 
There 
is no limit to the number of indexes that may be 
built for a C-ISAM file. 
Each index may have from 
one to eight parts, each of which may have a dif- 
ferent data type, each of which may be defined as 
having either ascending or descending order. 
Keys 
may be designated as allowing or not allowing dupli- 
cate values, as appropriate. 


Key value compression may also be used to op- 
timize file access. 
Optional leading duplicate 
character and trailing blank suppression, as well as 
duplicate key value suppression provides for a 
smaller index file on the disk, and thus faster file 
searches. 
This optimization is particularly impor- 
tant when indexes contain information such as city 
names, where duplicates and trailing blanks account 
for most of the bytes in the index pages. 
Also a 
derivative of the B+ tree architecture is used to 
optimize performance when reading next or previous 
records. 


The C-ISAM package is written entirely in the C 
programming language, and therefore can be utilized 
by any program which can itself call C-language 
functions. 
C-ISAM is also the data access method 
used by the INFORMIX Relational Database Management 
System. 
Therefore users of INFORMIX can access the 
C-ISAM files using its powerful query language, re- 
port writer, and transaction processing programs. 
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Finally C-ISAM offers some supplimentary func- 
tions that are not usually found in ISAM packages. 
A function call to provide a four byte unique record 
identifier is available for applications' whose 
records do not contain unique fields. 
Also an audit 
trail facility is provided which can be enabled or 
disabled at the programmer's discretion. 
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II. 
C-ISAM Calls in Summary 


isbuild(filename, recordlength, keydesc, mode) 
char *fi lename ; 
int record length; 
struct keydesc *keydesc; 
int mode; 


isopen(filename, mode) 
char *filename; 
int mode; 


isclose(isfd) 
int isfd; 


isaddindex(isfd, keydesc) 
int isfd; 
struct keydesc *keydesc; 


isdelindex(isfd, keydesc) 
int isfd; 
struct keydesc *keydesc; 


isstart(isfd, keydesc, length, record, mode) 
int isfd; 
struct keydesc *keydesc; 
int length; 
char *record; 
int mode; 


isread(isfd, record, 
mode) 
int isfd; 
char *record; 
int mode; 


iswrite(isfd, record) 
int isfd; 
char *record; 


isrewrite(isfd, record) 
int isfd; 
char *record; 


iswrcurr(isfd, record) 
int isfd; 
char *record; 
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isrewcurr(isfd, record) 
int isfd; 
char *record; 


isdelete(isfd, record) 
int isfd; 
char *record; 


isdelcurr(isfd) 
int isfd; 


isuniqueid(isfd, uniqueid) 
int isfd; 
long *uniqueid 


isindexinfo(isfd, buffer, number) 
int isfd; 
struct keydesc *buffer; 
int number; 


isaudit(isfd, filename, 
mode) 
int isfd; 
char *filename; 
int mode; 


iserase(filename) 
char *filename; 


islock(isfd) 
int isfd; 


isunlock(isfd) 
int isfd; 


isrelease (isfd) 
int isfd; 


isrename(oldname, newname) 
char *oldname; 
char *newname; 
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III. 
C-ISAM Call Formats and Descriptions 


Most calls to C-ISAM return either a a or -1 as 
the value of the function and set the global integer 
iserrno to either a or to an error indicator. 
In 
the case of isbuild and isopen, the return value 
will be a legal C-ISAM file descriptor or a -1. 
A 
-1 indicates that an error has occurred, and iserrno 
has been set. 
Also, the global characters isstat1 
and isstat2 are set for the convenience of integra- 
tion with COBOL. 
See Section XI, 
"Status Bytes and 
iserrno", for more information. 


Some parameters in this section are declared to 
be structure types that are explained further in 
Section XI of this document. 
Macros representing 
integer constants used as flags are also explained 
in Section XI. 


The structures keydesc and keypart (shown 
below) are used for index definition. 
When a C-ISAM 
file is built, a data file and an index file are 
created. 
The data file holds only data. 
The index 
file holds all of the pages of all of the indexes 
that are created. 
The index file also holds a small 
dictionary describing these indexes. 
isbuild and 
isaddindex use the keydesc and keypart structures to 
add the index definition to this dictionary. 
isstart uses the structures to determine which index 
is to be used to access the file in subsequent tran- 
sactions. 


struct keydesc 
{ 
short 
k flags; 
/* flags 
* / 
short 
k:nparts; 
/* number of parts in key */ 
struct keypart 
k_part[NPARTS]; 
/* each key part 
*/ 
} ; 


struct keypart 
{ 
short kp start; /* starting byte of key part */ 
short kp-Ieng; 
/* length in bytes 
*/ 
short kp:type; 
/* type of key part 
*/ 
} ; 
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In the keydesc structure, the integer k flags' 
is used to hold compression information for the in- 
dex that is being added, deleted or selected. 
The 
macros that are defined in isam.h should be used to 
indicate the compression techniques that are 
desired. 
If more than one of the compression 
features is used, the macro values are logically 
OR'ed together. 
The meaning of these macro values 
is: 


ISDUPS 
- duplicate values are allowed for this 
index 


DCOMPRESS - duplicate key values are to be 
compressed when they are stored 


LCOMPRESS - leading characters that are the same in 
one or more keys entries should be 
compressed 


TCOMPRESS - trailing blanks should be compressed 


COMPRESS 
- indicates that all of the compression 
techniques are to be used 


k nparts is an integer which indicates how many 
parts make up the index. 
These parts must be 
described in the k-part array of keypart structures. 
A keypart structure defines each part of the index 
individually. 
The number of elements in the k-part 


array should be equal to the integer value in 
k_nparts. 


The elements of the keypart structure are used 
as follows. 
kp start indicates the starting byte of 
the key part that is being defined. 
kp length is a 
count of the number of bytes in the part, and 
kp type designates the data type of the part. 
The 


types allowed by C-ISAM are defined in the header 
file isam.h (see Section X, The Header File isam.h). 
If this part of the key is in descending order, the 
type macro should be logically OR'ed to the ISDESC 
macro (defined in isam.h). 
For more information 
about creating and using indexes see Section V on 
key definition and manipulation and Section VI on 
key compression. 
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isbuild(filename, recordlength, keydesc, mode) 
char *filename; 
int recordlength; 
struct keydesc *keydesc; 
int mode; 


isbuild is used to create a C-ISAM file. 
This 
call causes two operating system files to be created 
and initialized. 
One of these two files, named by 
appending 
II .dat" to the filename parameter, will 
hold the data. 
The other, named by appending ".idx l1 
to the filename parameter, will hold the dictionary 
and the pages of the indexes' b-trees. 


After isbuild has completed successfully, the 
C-ISAM file will remain open for further processing. 
The isbuild function returns a C-ISAM file descrip- 
tor. 


The filename parameter should contain a null- 
terminated character string which is at least four 
characters shorter than the longest legal operating 
system file name. 


record length is the length of the record. 
Its 
value is the sum of the number of bytes in each 
field of the record. 
See Section IV for the length 
of each data type. 


All C-ISAM files are required to have a primary 
index. 
The keydesc parameter of this call should be 
used to specify the structure of the primary index. 
Additional indexes may be added later using 
isaddindex. 
See Sections V, VI, and VIII for more 
details on key definition and use. 


mode is used to specify locking information. 
The user-has three options - manual, automatic or 
exclusive. 
Selecting the manual option indicates 
that the user wishes to be responsible for locking 
records at the appropriate times using either the 
islock and isunlock calls, or the 
ISLOCK mode flag 
of the isread call and the isrelease function call. 
Selecting automatic locking indicates that the user 
wishes C-ISAM to lock each record at the time it is 
read and unlock each record after the next C-ISAM 
function call is made. 
Selection of exclusive lock- 
ing will deny file access to anyone other than this 
process. 
(More about locking can be found in Sec- 
tion VII.) 
The mode is specified by using the de- 
fine macros that are found in the header file 
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isam.h. 
A complete listing of this file appears in 
Section X of this document. 
Modes that are used in 
the isbuild call are: 


12 


One of these, arithmetically 
added to 


ISEXCLLOCK 
ISMANULOCK 
ISAUTOLOCK 


one of these: 


ISINPUT 
ISOUTPUT 
ISINOUT 
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isopen(filename, mode) 
char *filename; 
int mode; 


isopen is used to open a C-ISAM file for pro- 
cessing. 
The function will return the C-ISAM file 
descriptor that should be used in sUbsequent 
accesses to the C-ISAM file. 


This call will automatically position the 
current record pointer to the first record in order 
of the primary index. 
If another ordering is 
desired, the isstart call can be used to select 
another index. 


The filename parameter must contain a null- 
terminated string, which is the file name of the C- 
ISAM file to be processed. 


mode determines the locking information. 
The 
user has three options - manual, automatic or ex- 
clusive. 
Selecting the manual option indicates that 
the user wishes to be responsible for locking 
records at the appropriate times. 
Selecting au- 
tomatic locking indicates that the user wishes C- 
ISAM to lock each record as it is read and unlock it 
after any subsequent C-ISAM function calls. 
Selec- 
tion of exclusive locking will deny file access to 
anyone other than this process. 
More about locking 
can be found in Section VII. 
The mode parameter 
also specifies whether the file is-ro-be opened for 
read, write or read/write access. 


mode is specified by using the define macros 
that are found in the header file isam.h. 
A com- 
plete listing of isam.h appears in Section X of this 
document. 
Modes that are used in the isopen commanc 
are: 


One of these, arithmetically 
added to 


ISEXCLLOCK 
ISMANULOCK 
ISAUTOLOCK 
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one of these: 


ISINPUT 
ISOUTPUT 
ISINOUT 
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isclose(isfd) 
int isfd; 


isclose is used to close a C-ISAM file. 
Any 
locks that are held for the file by the process is- 
suing the isclose call are released. 


NOTE: It is extremely important to close C-ISAM 
files after processing has finished, especially on 
operating systems without file locking system calls. 
On these systems, failure to close C-ISAM files us- 
ing the isclose function will leave the files 
locked. 
See the discussion in this manual concern- 
ing locking and system-crash recovery in Section 
VII. 
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isaddindex(isfd, keydesc) 
int isfd; 
struct keydesc *keydesc; 


isaddindex is used to add an index to a C-ISAM 
file. 
The index will be built for the C-ISAM file 
indicated by the isfd parameter and will be defined 
according to the information in the keydesc struc- 
ture. 
This call will execute only if the C-ISAM 
file has been opened for exclusive access. 


There is no limit to the number of indexes that 
may be added through the isaddindex call. 
However, 
the maximum number of parts which may be defined for 
an index is eight (8). 
Also the maximum number of 
bytes which can exist in an index is 120. 


Use of this call and index use in general are 
explained in Section V on index definition and mani- 
pulation. 
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isdelindex(isfd, keydesc) 
int isfd; 
struct keydesc *keydesc; 


One of these, arithmetically 
added to 


ISEXCLLOCK 
ISMANULOCK 
ISAUTOLOCK 


one of the se : 


ISINPUT 
ISOUTPUT 
ISINOUT 


isdelindex is used to remove an existing index. 
The index will be removed from the C-ISAM file indi- 
cated by isfd. 
The index to be removed will be de- 
fined py the information in the keydesc structure. 
All indexes may be deleted except the primary index. 
Attempts to delete the primary index will cause a -1 
error code to be returned and the iserrno global in- 
teger to be set. 
This call will execute only if the 
C-ISAM file has been opened for exclusive access. 
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isstart(isfd, keydesc, length, record, mode) 
int isfd; 
struct keydesc *keydesc; 
int length; 
char *record; 
int mode; 


isstart selects the index to be used in subse- 
quent operations. 
The key value to be sought should 
be placed in the record parameter, in the positions 
described by the keydesc parameter. 
The keydesc 
structure must describe an index which has been pre- 
viously added using the isaddindex call. 


length is used to specify the part of the key 
to be considered significant when doing the search. 
A zero indicates that the whole key is significant; 
a positive value is used to indicate a shorter 
length. 
If length is greater than zero, 
C-ISAM will 
respond during searches as if the index were origi- 
nally defined to have that shorter length. 


mode may be ISFIRST, 
ISLAST, 
ISEQUAL, 
ISGREAT 
or ISGTEQ. 
It is used to position the user in the 
file in association with the index selected by the 
keydesc argument. 


ISFIRST positions the user's program in the C- 
ISAM file just before the first record in the order- 
ing of the index specified in the keydesc parameter. 
A subsequent call toisread using the ISNEXT mode 
parameter reads the first record in the current ord- 
ering. 


ISLAST positions the user's program just after 
the last record in that ordering. 
A subsequent call 
to isread using the ISPREV mode parameter reads the 
last record in the current ordering. 


Note that if mode is ISFIRST or ISLAST the 
parameters, length and record are unneeded and are 
not used by the isstart call. 


Use of the ISEQUAL, 
ISGREAT, or ISGTEQ modes 
are different from the use of the ISFIRST or ISLAST 
modes. 
When using the former group of modes, the 
user's program must place the key value to be 
searched for in the record buffer before calling 
isstart. 
The value to be searched for must be 
placed in the exact location in the record buffer 
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where the keydesc parameter claims the index exists. 


ISEQUAL will give one of two possible results. 
It will either find a record whose key value is 
equal to that found in the appropriate positions of 
the record buffer parameter, or it will return an 
error code (-1) and set iserrno to ENOREC. 
The er- 
ror code ENOREe indicates that no record, which has 
the key value specified in the record buffer parame- 
ter, exists in the file. 


ISGREAT will also give one of two responses. 
ISGREAT will either find the next higher record 
whose key value is greater than that found in the 
appropriate locations of the record buffer parame- 
ter, or isstart will return an error condition (-1) 
and set iserrno to ENOREC. 


The ISGTEQ mode parameter finds the record 
which has the next higher key value greater than or 
equal to the key value specified in the appropriate 
positions of the record buffer parameter. 
If no 
such record is found, isstart returns an error code 
(-1) and sets iserrno to ENOREC. 


The above "define" macros, 
ISFIRST, 
ISLAST, 
ISEQUAL, 
ISGREAT, and ISGTEQ, can be found in the 
header file isam.h. 
A complete listing of isam.h 
appears in Section X of this document. 


isstart can also be used for sequential access 
by specifying a previously defined key that has zero 
parts; that is, give a value to keydesc to designate 
a structure in which k_nparts = O. 


isstart performs two basic functions. 
It 
selects the index which is to be used for subsequent 
reads, and it finds (but does not read) a record in 
the C-ISAM file. 
isread, on the other hand, both 
finds and reads records in a C-ISAM file. 
isstart 
need not be used to find each record before it is 
read using isread. 
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isread(isfd, record, mode) 
int isfd; 
char *record; 
int mode; 


isread is used to read records sequentially or 
randomly as indicated by the mode parameter. 


When sequential processing is desired, 
mode· is 
used to indicate that the current (ISCURR), first 
(ISFIRST), last (ISLAST), next (ISNEXT) or previous 
(ISPREV) record is to be read. 
When random selec- 
tion is desired, mode is used to indicate that the 
record to be returned must have a value that is 
equal to (ISEQUAL), greater than (ISGREAT), or 
greater than or equal to (ISGTEQ) the specified 
search value. 
The search value is placed in the 
record array in the correct byte positions. 
isread 
will fill in the record with the results of the 
search. 
The mode is specified by using the "define" 
macros that are found in the header file isam.h. 
A 
complete listing of this file appears in Section X 
of this document. 


If manual locking was specified when the file 
was opened and the record is to be locked before be- 
ing read, the ISLOCK flag may be arithmetically ad- 
ded to one of the above macros. 
The record will 
then remain locked until unlocked with the isrelease 
call. 
Entire C-ISAM files may be locked and un- 
locked by using the islock and isunlock calls. 
Modes that are used in the isread call are: 


One of these, optionally 
added arithmetically 
to: 


ISCURR 
ISNEXT 
ISFIRST 
ISGREAT 
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ISEQUAL 
ISPREV 
ISLAST 
ISGTEQ 


ISLOCK 
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iswrite(isfd, record) 
int isfd; 
char *record; 


iswrite writes the record passed to it in the 
record parameter to the data file. 
The appropriate 
values will be inserted into the index file for each 
index that is defined. 


iswrite does not change the position of the 
current record pointer. 
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isdelete(isfd, record) 
int isfd; 
char *record; 


isdelete deletes the record passed to it in the 
record parameter from the C-ISAM file. 
If the pri- 
mary key had been declared unique when the index was 
created, isdelete uses the primary key to determine 
which record should be deleted. 
Otherwise, isdelete 
returns an error code (-1). 
(If the index on the 
primary key values is not unique, the record to be 
deleted should first be found using isread and then 
isdelcurr should be called to delete the record.) 


The appropriate values will be deleted 
index file for each index that is defined. 
does not change the position of the current 
pointer. 


C-ISAM 


fi~t~ 
isdelete 
record 
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isrewrite(isfd, record) 
int isfd; 
char *record; 


isrewrite is used to change one or more values 
for a record that is already in the C-ISAM file 
identified by the file identified by isfd. 
The pri- 
mary key is used to determine which record should be 
changed and the record parameter contains the 
changes. 
The primary key value must be unique and 
may not be changed. 
The whole record is written to 
the data file. 
Only the changed index values will 
be rewritten to the index file for each index that 
is defined. 


This is consistent with COBOL requirements for 
maintaining the order of records in duplicate 
chains. 
isrewrite does not change the position of 
the current record pointer. 
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isdelcurr(isfd) 
int isfd; 


isdelcurr differs from isdelete in that it 
deletes the current record from the C-ISAM file, 
rather than the record indicated by the primary key. 
The appropriate values will be deleted from the in- 
dex file for each index that is defined. 
This call 
is useful when the primary key is not unique, and 
the record cannot be located and deleted in one 
call, as in the case of isdelete. 
isdelcurr deletes 
the record most recently found in the C-ISAM file 
described by the isfd parameter. 
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isrewcurr(isfd, record) 
int isfdj 
char *recordj 


isrewcurr is used to change one or more values 
for the current record. 
It uses the data found in 
the character array record to rewrite the record 
most recently found in the C-ISAM file described by 
the isfd parameter. 
The appropriate values will be 


rewritten to the index file for each index that is 
defined. 
The primary key value may be changed. 
isrewcurr is useful when the primary key is not 
unique, and the record cannot be located and rewrit- 
ten in one call, as in the case of isrewrite. 
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isuniqueid(isfd, uniqueid) 
int isfd; 
long *uniqueid; 


isuniqueid is used to return a long integer 
that is guaranteed to be unique for the C-ISAM file. 
This is useful if a unique identifier for each 
record is desired. 


Often a programmer may want to use the calls 
which require a unique primary index, but may have 
no reasonably-sized portion of the data record which 
is quaranteed to be unique. 
In such a case, 
a por- 
tion of the record could contain the serially- 
incremented four-byte long integer returned by 
isuniqueid. 
It is the responsibility of the pro- 
grammer to place the unique long integer in the 
record buffer using stlong (see Section V for the 
syntax of stlong) before a write or rewrite call is 
made. 
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isindexinfo(isfd, buffer, number) 
int isfd; 
struct keydesc *buffer; 
/* 
buffer may be a pointer to a */ 
/* 
dictinfo structure instead. 
*/ 
int number; 


isindexinfo gives the caller access to informa- 
tion about the C-ISAM file, 
such as information 
about the defined indexes, their location within the 
record, their length and whether duplicate values 
are allowed. 


Information about a particular index is ob- 
tained by specifying the number of the index using 
the number parameter. 
General information such as 
the number of indexes, 
index record size, and data 
record size is obtained by calling isindexinfo wi th 
the number parameter set to ° and reading the buffer 
into a structure of type dictinfo. 


buffer can contain information in the format of 
either keydesc or dictinfo depending on whether the 
number parameter is positive or 0, respectively. 
As 
indexes are added and deleted, the number of a par- 
ticular index may vary. 
To ensure review of all 
indexes, 
loop over the number of indexes indicated 
in dictinfo (see structure definitions in Section X 
of this document). 
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isaudit(isfd, filename, 
mode) 
int isfd; 
char *filename; 
int mode; 


isaudit is used to perform operations involving 
the audit trail. 
Using this call, the audit trail 
can be started or stopped, and the audit trail file 
name (filename parameter) can be set or retrieved. 
The programmer can also determine whether the audit 
trail is on or off. 


mode is used to specify which operation is 


desir~ mode is specified by using the "define" 
macros found in the header file isam.h. 
A complete 
listing of isam.h appears in Section X of this docu- 
ment. 
Modes that are used in the isaudit command 
are: 


AUDSTART 
AUDSTOP 
AUDSETNAME 
AUDGETNAME 
AUDINFO 


When the AUDINFO flag is passed in the mode 
parameter, the first byte of the filename parameter 
(filename[O]) will be set to a 0 (the number, not 
the character) to indicate that the audit trail is 
off, or 1 to indicate that the audit trail is on. 


When an audit trail is started for the first 
time, the audit trail file is created. 
Its name is 
stored in the file filename.idx. 
When an audit 
trail is stopped the audit trail file is not erased, 
but the recording of subsequent transactions is 
suspended. 
When an audit trail is started and the 
designated audit trail file already exists, it 
remains intact, and each subsequent transaction is 
once again appended to the end of the file. 
An au- 
di t trail may be "re-started" by erasing the audit 
trail file and starting the audit trail anew. 
The 
audit trail file name may be any operating system 
file name or pathname. 


The contents of an audit trail record will vary 
depending on the operating system on which C-ISAM is 
running. 
The record will contain at least the data 
record which was added or deleted. 
Rewrites will be 
recorded with both a before and after image. 


\. 
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On UNIX operating systems, the record will be 
preceeded by the following pieces of information 
(where the integers are stored in the order high 
byte flow byte): 


A, 
D, R or W (for add, delete, read version, 
written version) 
date and time (coded as one long integer) 
process id (short integer) 
user id (short integer) 


On MS-DOS operating systems, the integer data are 
all zeros. 


28 
C-ISAM 


I 
•I, 
l 


iserase(filename) 
char *filename; 


iserase will remove the filename.idx and 
filename.dat files that comprise the C-ISAM file, as 
well as all associated audit trail files. 
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islock(isfd) 
int isfd; 


islock will lock the entire file that is speci- 
fied by isfd. 
More discussion of locking can be 
found in Section VII of this manual. 
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isunlock(isfd) 
int isfd; 


isunlock is used to release an existing file- 
level lock for the file specified by the file 
discriptor isfd. 
Further discussion of locking can 
be found in Section VII of this manual. 
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isrelease(isfd) 
int isfd; 


isrelease unlocks records which have been 
locked using the 
ISMANULOCK mode in the isread call. 
All locked records in the file indicated by isfd 
will be unlocked. 
More information, including exam- 
ples of how to use isrelease, can be found in Sec- 
tion VII of this manual. 
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isrename(oldname, newname) 
char *oldname; 
char *newname; 


isrename will rename the C-ISAM file system 
specified by the oldname parameter to the name 
specified by the newname parameter. 
Audit trail 
files will not be renamed, since their names are not 
logically tied to the C-ISAM file name. 
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IV. 
Data Types 


The types of data which can be defined and 
manipulated using C-ISAM are described in this sec- 
tion. 
Descriptions of how each data type is stored 
in data files and how each data type must be treated 
are also discussed. 


The data types for which C-ISAM can maintain 
properly ordered indexes are type character, 2 byte 
integers, 
4 byte integers, machine float (floating 
point), and machine double 
(double precision float- 
ing point). 
The macro definitions used to describe 
these types to C-ISAM are shown below. 
These defin- 
itions can also be found in 1sam.h. 


CHARTYPE 
INTTYPE 
LONGTYPE 
FLOATTYPE 
DOUBLETYPE 


CHARTYPE 


character 
2 byte integer 
4 byte integer 
machine float 
machine double 


The data type CHARTYPE signifies to C-ISAM that 
a particular region of a data file consists of byte 
values from 0 to 255. 
A typical example of the data 
type CHARTYPE is a city name or an address field. 


INTTYPE and LONGTYPE 


The data types INTTYPE and LONGTYPE consist of 
2 and 4 byte binary signed integer data. 
Integer 
data is always stored in the data and index files as 
high/low, most significant byte first, least signi- 
ficant byte last. 
This storage technique is in- 
dependent of the form in which integers are stored 
in the machine on which C-ISAM is executing. 
There- 
fore, depending on the operating environment, the 
format of storage for integers in the data and index 
files may differ from the format of storage for in- 
tegers stored in executing programs. 
For this rea- 
son four routines are supplied to the user of C-ISAM 
for the conversion to and from C-ISAM integer 
storage format. 
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The four format conversion routines for in- 
tegers are: 


Idint(p) 
returns a machine-format integer; p is 
a char pointer to the starting byte of 
a C-ISAM-format INTTYPE 


stint(i, p) 
stores a machine-format integer i as a 
C-ISAM-format INTTYPE at location p 
where p is a char pointer to the first 
byte of a C-ISAM-format INTTYPE 


Idlong(p) 
returns a machine-format LONGTYPE; p is 
a char pointer to the first byte of C- 
ISAM-format LONGTYPE 


stlong(l, p) stores a machine-format integer i as a 
C-ISAM-format LONGTYPE at location p 
where p is a char pointer to the first 
byte of a 
C-ISAM~format LONGTYPE 


These routines are either macros defined in isam.h 
or are in the isam library. 


The typical use for the above routines occurs 
after a C-ISAM data record has been read into the 
user buffer. 
Integer values which are to be used by 
the user program first have to be converted to 
machine usable forffiat by using Idint() for type 
INTTYPE and ldlong() for LONGTYPE, as illustrated 
below: 


int 
int machine; 
long long machine; 
char *p_cIsam_int, *p_cisam_long; 


int machine 
long_machine 
ldint(p cisam int); 
ldlong(p_cisam_long); 


Storage of machine-format integer data as C-ISAM- 
format integer data requires the use of the stint() 
and stlong() routines: 


stint(int machine, p cisam int); 
stlong(long_machine,-p_cisam_long); 
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Note that the C-ISAM formatted integers need not be 
aligned along word boundaries as do machine format- 
ted integers. 


FLOATTYPE and DOUBLETYPE 


The data type FLOATTYPE and DOUBLETYPE are the 
two floating point data types. 
The data type 
FLOATTYPE is the same as the C data type float while 
the data type DOUBLETYPE is the same as the C data 
type double. 
Both data types differ in length and 
format from machine to machine. 
There is no differ- 
ence between the floating point format used by C- 
ISAM in each operating environment and its counter- 
part in the C language except that C-ISAM floating 
point numbers may be placed on non-word boundaries. 
For this reason, four more routines, located in the 
isam library, have been provided to the C-ISAM user 
to retrieve or replace these non-aligned floating 
point numbers from their positions in C-ISAM data 
records. 
These routines are: 


Idfloat(p} 
returns a machine-format float; p is a 
char pointer to the starting byte of a 
C-ISAM-format FLOATTYPE 


stfloat(f, p} stores a machine-format float f at lo- 
cation p where p is a char pointer to 
the starting (leftmost) byte of a C- 
ISAM-format FLOATTYPE 


Iddbl(p} 
returns a machine-format double; p is 
a char pointer to the starting byte of 
a C-ISAM-format DOUBLETYPE 


stdbl(d, p} 
stores a machine-format double d as a 
C-ISAM-format DOUBLETYPE at location p 
where p is a char pointer to the 
starting (leftmost) byte of a C-ISAM- 
format DOUBLETYPE 


The use of the floating point load and store 
routines is analogous to the use of the integer load 
and store routines. 
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v. 
Index Definition and Manipulation 


The C language structures which describe an in- 
dex to any given C-ISAM function call are the 
keydesc and keypart structures. 
These structures 
are shown below. 
They are also defined in the file 
isam.h which must be included in any program which 
uses C-ISAM function calls. 


struct keydesc 
{ 
short k flags; 
/* describes compression 
*/ 
short k-nparts; /* number of parts in this key */ 
struct keypart 
k_part[NPARTS]; /* each key part 
*/ 
}; 
/* 
(8 possible) */ 


struct keypart 
{ 
short kp start; /* starting byte of key part 
*/ 
short kp-Ieng; 
/* length in bytes of key part */ 
short kp:type; 
/* type of key part 
*/ 
} ; 


It is the purpose of this section to show how 
to initialize the keydesc structure for use with any 
of the C-ISAM functions that require it as a parame- 
ter. 


The first sample index to be described here has 
one part which has the data type of integer. 
In- 
tegers are 2 bytes; therefore, the length of the in- 
dex is 2 bytes. 
The index begins in the first byte 
of the record. 
No data compression is desired for 
keys stored in this index's b-tree index files. 
The 
order of the index is to be ascending (lowest key 
value to highest key value). 
Finally, duplicate key 
values for this index are not to be allowed by C- 
ISAM. 


The C program to add the index described above 
is shown on the next page. 
It is assumed that the 
file system "myfile" has already been created using 
the isbuild C-ISAM function call. 
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#include <isam.h> 


struct keydesc first_key; 
int fd; 


maine ) 
{ 
/* In order to add an index to a C-ISAM file system 
"myfile". the file system must be opened wi th 
exclusive access. 
Therefore. 
ISEXCLLOCK must be 
must be arithmetically added to the mode 
parameter. 
*/ 


if «fd 
= isopen("myfile". 
ISINOUT+ISEXCLLOCK)) < 0) 
{ 
printf("Open error 
%d on myfile.\n". iserrno); 
exi t( 1) ; 
} 
mkfirst key(); 
if (isclose(fd)) 
{ 
printf("Close error 
%d on myfile.\n". iserrno); 
exit(1); 
} 


mkfirst key() 
{ 
- 
first key.k flags 
= 0; 
first:key.k:nparts = 1; 
/* no dups, 
no compression */ 
/* this index has one part */ 


/* The starting byte of an index is always defined 
as the byte offset from the beginning of the 
record. 
Since this index begins at the begin- 
ning of the record, its byte offset is zerO. 
*/ 


first key.k part[O].kp start 
= 0; 
/* offset is zero */ 
first-key.k-part[O].kp-type 
INTTYPE; /* data type 
- 
- 
- 
is integer */ 
first_key.k_part[O].kp_leng = 2; 
/* 2 byte integer */ 


if (isaddindex(fd, &first key)) 
/* add the index 
*/ 
{ 
- . 
printf( "Error in adding first_key index: iserrno 
%d. \n", 
iserrno) ; 
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Note that, in the previous example, the struc- 
ture element k flags is initialized to zero. 
This 
indicates that-no special characteristics are to be 
attributed to this index. 
Since k flags is zero, 
duplicate key values will not be allowed by C-ISAM. 
Also no compression will be performed on key values 
as they are placed in the b-tree index (.idx) file. 
If duplicate key values were to be allowed, 
k flags 
should have been initialized to ISDUPS as in the 
following statement: 


first key.k flags = ISDUPS; 
- 
/* allow duplicate key values */ 


If duplicate key value compression had been 
desired, k flags should have been initialized to 
ISDUPS 
+ DCOMPRESS. 
This would allow duplicate key 
values and would force those key values to be 
compressed in the b-tree index files. 


first_key.k_flags = ISDUPS 
+ DCOMPRESS; 


Note, also, that the index defined by the 
keydesc structure first key has only one part. 
The 
number of key parts which make up the index is de- 
fined by the structure element k nparts, which in 
the above example is initialized-to one. 


first key.k nparts = 1; 
- 
/*-this index has one part */ 


In the previous example, the index defined had 
only one part. 
That part had a data type of in- 
teger. 
However, a particular application could re- 
quire that a multi-part index be used. 
Within the 
keydesc structure there exists an array of keypart 
structures. 
Each keypart structure defines one part 
of the inde.x. 
It holds the starting byte offset 
from the beginning of the record, 
the part's length, 
and the part's data type. 
In order for a multi-part 
index to be described to C-ISAM, 
the user's program 
must initialize each of these structures to reflect 
the desired position, length and data type for each 
index part. 
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struct keypart 
{ 
short kp start; 
short kp-Ieng; 
short kp:type; 
} ; 


/* starting byte 
*/ 
/* length in bytes 
*/ 
/* type 
*/ 


In the following example program a three part 
index is defined. 
The index consists of a character 
field, 
a long, and another character field. 
It is 
important to note that the parts of an index need 
not be contiguous within a record, nor do the parts 
of an index have to exist in any particular order 
within the record. 
In other words, 
C-ISAM puts no 
restrictions on where the parts of an index exist in 
the record. 
However, the maximum number of key 
parts which may be defined for an index is eight 
(8), and the total number of bytes within an index 
may not exceed 120. 
There is no limit to the number 
of keys that may be added to a C-ISAM file. 
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#include <isam.h> 


st~uct keydesc second_key; 
int fd; 


maine ) 
{ 
if «fd = isopen("myfile", 
ISINOUT.ISEXCLLOCK)) 
< 0) 
{ 


p~intf("Open 
e~~o~ Id on myfile.\n", 
ise~~no); 
exit(1); 
) 
mksecond key(); 
if (isclose(fd)) 
{ 


p~intfj"Close 
e~~o~ 
%d on myfile.\n", 
ise~~no); 
exit(1); 
} 


mksecond key() 
{ 
- 
second key.k flags 
= ISDUPS • COMPRESS; 
- 
/* allow dups, full 
comp~ession */ 


second_key.k_npa~ts = 3; /* this index has 3 
pa~ts */ 


/* define the 
fi~st index 
pa~t */ 
second key.k 
pa~t[O].kp sta~t = 15; 
second-key.k-pa~t[O].kp-leng= 8; 
second=key.k=pa~t[O].kp=type= CHARTYPE; 


/* define the second index 
pa~t */ 
second key.k 
pa~t[1].kp sta~t = 30; 


second-key.k-pa~t[1].kp-leng= 4; 


second=key.k=pa~t[1].kp=type= LONGTYPE; 


/* define the 
thi~d index 
pa~t */ 
second key.k 
pa~t[2].kp sta~t = 3; 
second-key.k-pa~t[2].kp-leng= 6; 
second=key.k=pa~t[2].kp=type= CHARTY?E • ISDESC; 
if (isaddindex(fd, &second key)) 
{ 
- 


p~intf("E~~o~ in adding second_key index: 
ise~~no = Id.\n", 


ise~~no) ; 
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VI. 
Index Compression 


This section discusses key value compression, 
what types of key compression are available and how 
to use them, and why key compression improves per- 
formance. 


C-ISAM has the capacity to compress key values 
held in the b-tree index files. 
In addition to disk 
space savings, key compression can substantially im- 
prove real time response to random access requests. 
This improvement in performance is accomplished by 
increasing the number of key values which can be 
he ld in a b-tree page. 
With more key value s per b- 
tree page fewer disk accesses are neccessary to find 
any given data record. 
Since disk accesses consume 
the overwhelming percentage of real time during file 
accesses, key compression in b-tree files can con- 
siderably improve real time response. 


This improvement becomes more dramatic as field 
size increases and where duplicate values, leading 
duplicate characters, and trailing blanks become a 
large percentage of the characters of the key. 


The following illustrations show the three 
types of compression which may be chosen for an 
index--TCOMPRESS, 
LCOMPRESS, and DCOMPRESS. 
-The 
illustration below shows the effect of leading char- 
acter compression, 
LCOMPRESS, on a group of sur- 
names. 
Leading character compression carries an 
overhead (indicated by #) of one byte per field. 


Key Value 
Compressed with LCOMPRESS 
Bytes Saved 


Abbot•...•...•...••• #Abbot............... 
-1 
Able •••••••...... '" 
#le... .•..•........ 
1 
Acre ••.•..•.••.•.• " 
#cre................ 
0 
Albert 
#lbert.............. 
0 
Albertson •••.•..••.. #son........... 
5 
Morgan •.........•... #Morgan.............. 
-1 
McBride .•.....••.... #cBride............. 
0 
McCloud 
#Cloud............. 
1 
Richards ....•.•..... #Richards............ 
-1 
Richardson 
#on.......... 
7 


200 bytes 
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189 bytes 
11 bytes 
5.5 % 
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The illustration above shows that with the use 
of leading compression alone a savings of 5.5 per- 
cent in b-tree page size can result. 
Much more 
dramatic savings can result if trailing blanks are 
compressed as well. 
Assuming a field length of 20, 
the page size savings from using both TCOMPRESS and 
LCOMPRESS is 67.5 percent. 
Again, trailing compres- 
sion has an overhead (indicated by #) of one byte 
per field. 


Key Value 
Compressed with LCOMPRESS 
Bytes Saved 
+ 
TCOMPRESS 


Abbot ••••••• ~••••••• 
Able •••••.••••.••••• 
Acre •••••••••••••••• 
Albert ••.••.•••.•.•• 
Albertson •••..•••••• 
Morgan •••••••.•••••• 
McBride ••••••••••••• 
McCloud ••••••••.•••• 
Richards •.•••••.•••. 
Richardson •.••••.... 


200 bytes 


##Abbot 
##le 
##cre 
##lbert 
##son 
##Morgan 
##cBride 
##Cloud 
##Richards 
/I#on 


65 bytes 


13 
16 
15 
13 
15 
12 
12 
13 
10 
16 


135 bytes 
67.5 % 


The final compression method which can be used 
to compress key values within b-tree pages is dupli- 
cate compression. 
DCOMPRESS can be used for an in- 
dex which allows duplicate key values. 
Duplicate 
compression eliminates duplicate entries for the 
same key value. 
Fields holding cities or states are 
often duplicate intensive. 
An illustration of this 
compression method follows: 
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Key Value 
Compressed with LCOMPRESS 
Bytes Saved 
+ 
TCOMPRESS 
+ 
DCOMPRESS 


Abbot•••......•..•.• 
##Abbot 
13 
Abbot•...•.••....•.. 
(no entry) 
20 
Abbot•.•..•..••..•.• 
(no entry) 
20 
Able ••.••••..•....•. ##le 
16 
Able •.•.•.•......••• 
(no entry) 
20 
Acre •.........•••.•. ##cre 
15 
Albert•..•.•..••••.. ##lbert 
13 
Albertson..•.•...•.. ##son 
15 
Albertson..•••..•••• 
(no entry) 
20 
Morgan .••.....•.••.. ##Morgan 
12 
McBride .•.••...•.... ##cBride 
12 
McCloud ••.......••.• ##Cloud 
13 
Richards...•.•.....• ##Richards 
10 
Richardson ••........ ##on 
16 
Richardson •••••..•.. 
(no entry) 
20 


300 bytes 
55 bytes 
235 bytes 
78.3 % 


Finally, if the user wishes all compression 
techniques to hold for a particular index, the macro 
COMPRESS may be used. 
Using COMPRESS is identical 
to assigning the expression TCOMPRESS 
+ DCOMPRESS 
+ 
LCOMPRESS to the k flags structure element of the 
keydesc structure.- 
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VII. 
Locking 


There are two levels of locking available from 
C-ISAM--file level locking, and record level lock- 
ing. 
Within these two levels C-ISAM offers several 
methods from which the user may choose to best suit 
application requirements. 


Exclusive File Locking 


File locking may be accomplished in two ways. 


One method prevents other processes from either 
reading from or writing to a given C-ISAM file. 
This method is referred to as an "exclusive" lock 
and remains in effect from the moment the file is 
opened, using isopen or isbuild, until the file is 
closed using isclose. 
Exclusive file locking is 
specified by adding ISEXCLLOCK to the mode parameter 
of the isopen or isbuild function call. 
Exclusive 
file level locking is not necessary for most situa- 
tions, but it must be used when an index is being 
added using isaddindex, or when an index is being 
deleted using isdelindex. 
The skeleton program 
shown below illustrates how exclusive file level 
locking is done: 


myfd = isopen("myfile", 
ISEXCLLOCK+ISINOUT); 


. 
isclose (myfd); 


Manual File Locking 


The other file level locking method prevents 
other processes from writing to a given C-ISAM file, 
but allows other processes to read the locked C-ISAM 
file. 
This kind of file level locking is specified 
by use of the islock and isunlock function calls. 
When a C-ISAM file is to be locked in this manner, 
C-ISAM must first be notified of the user's inten- 
tion to use manual locking. 
This is done by adding 
ISMANULOCK to the mode parameter of the isopen or 
isbuild call. 
Later in the program, when locking is 
desired, 
islock should be called to lock the file. 
When the file is to be unlocked, 
isunlock should be 
called. 
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myfd 
isopen(»myfile», 
ISMANULOCK+ISINOUT); 
·· 
(»myfile» is unlocked here) 
· 
islock(myfd) ; 
·· 
(»myfile» is locked here) 
· 
isunlock(myfd); 
·· 
("myfile» is unlocked here) 
· 
isclose (myfd) ; 


Record Level Locking 


There are two basic types of record level lock- 
ing implemented in C-ISAM--Automatic and Manual. 


Automatic record locking locks a record just 
before it is read using the isread call. 
It unlocks 
the record after the next C-ISAM call has completed. 
Automatic record locking is used when the user wants 
to lock one record at a time and is unconcerned 
about when or for 
how long that record will be 
locked. 


Manual record locking, on the other hand, 
can 
lock any number of records. 
Manual locking locks a 
record when that record is read using isread. 
It 
unlocks that record, and any other records that are 
currently locked, when isrelease is called. 
Manual 
record locking is used when more control is required 
over when a record, or set of records, is to be 
locked and unlocked. 


Both automatic and manual locking techniques 
allow other processes to read records locked by the 
current process, but they may not lock, re-write, or 
delete them. 
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Automatic Record Locking 


Automatic record locking must be specified to 
C-ISAM when the file is opened. 
This is done by ad- 
ding ISAUTOLOCK to the mode parameter of the isopen 
or isbuild function call. 
From when the file is 
opened until it is closed, every record will be 
locked automatically before it is read. 
Each record 
remains locked until the next C-ISAM function call 
is completed for the current file. 
Therefore, while 
using the automatic record locking mechanism of C- 
ISAM, only one record per C-ISAM file may be locked 
at a given time. 
An illustration which shows how 
automatic record locking is used is shown below: 


myfd 
isopen("myfile", 
ISINOUT+ISAUTOLOCK); 


isread(myfd, myrecord, 
ISNEXT); 
/* record locked here */ 
/* before record is read */ 
. 
isrewcurr(myfd, myrecord); 
/* record unlocked here */ 
/* after completion 
*/ 
. 
isclose(myfd); 


Manual Record Locking 


The user's intention to use manual record lock- 
ing must be specified before any processing takes 
place. 
This is done by adding ISMANULOCK to the 
mode parameter of isopen or isbuild function calls 
when the file is opened. 
After the file is open, if 
the user wishes a record to be locked, 
ISLOCK must 
be added to the mode parameter of the isread func- 
tion call which is reading that record. 
Each and 
every record which is read in this manner remains 
locked until,they are all unlocked by a call of the 
isrelease function of C-ISAM. 
The number of records 
which may be locked in this manner at anyone time 
is operating system dependent. 
The following illus- 
tration shows how a number of records in a particu- 
lar file are locked and unlocked using manual record 
locking: 
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myfd 
isopen("myfile", 
ISINOUT+ISMANULOCK); 


· 
isread(myfd, first_record, 
ISEQUAL+ISLOCK); 


· 
isread(myfd, second_record, 
ISEQUAL+ISLOCK); 


· 
isread(myfd, third_record, 
ISEQUAL+ISLOCK); 


· 
isrelease (myfd) ; 
/* unlock all three records */ 
· 
isclose (myfd) ; 


Setup and Maintenance of C-ISAM's Locking System 


Depending on the operating environment, locking 
in C-ISAM is implemented in one of two ways. 
Where 
the operating environment has a locking call as part 
of the operating system kernel, 
C-ISAM uses that 
call to optimize the locking of files and records. 
Where the operating environment does not have a 
locking system call, 
C-ISAM creates and manipulates 
a system of files which work in the absence of a 
true operating system locking call. 
On systems 
where there is no locking call available there is a 
little more required of the user in terms of initial 
setup and maintenance than on systems where the 
operating system provides a locking call. 
It is the 
purpose of this section to describe the setup and 
maintain C-ISAM's locking system. 


In order for the C-ISAM locking feature to work 
properly, the user must create a directory off of 
the root directory called /isam. 
This directory 
must be readable, writable, and executable (accessi- 
ble) to everyone, so it must have a mode of 0777. 
This is done with the two simple UNIX commands mkdir 
and chmod as shown below: 
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% mkdir fisam 
% chmod 0777 fisam 


The /isam directory is used to prevent any two 
processes from entering the C-ISAM code at the same 
time. 
It thus provides C-ISAM with a semaphore for 
those systems which do not have a locking call as 
part of the kernel. 


When a C-ISAM file is created using isbuild 
there are three files created which physically 
represent that file. 
These files are the data file, 
the index file, 
and the lock file (in the case of 
the systems without an operating system locking 
call). 
The C-ISAM file's three file names are con- 
structed from the file name itself followed by the 
suffix lI.dat ll for the data file, 
lI.idx ll for the in- 
dex file, 
and 1I.10k ll for the lock file. 
(Users 
whose C-ISAM systems do not create the lock file 
need not read any further.) 


The lock file holds information about which 
processes have which records locked. 
It also 
describes the type of lock (i.e. exclusive or 
shared) which currently exists for the file. 
The 
lock file's contents changes whenever a process 
locks a record or file. 
The only way C-ISAM knows 
whether records are locked is by looking in the lock 
file. 


This locking technique creates a problem if a 
computer failure occurs while a process has a record 
or file locked. 
This problem exists because the 
lock file says there are records locked by processes 
which no longer exist. 
Since the processes no 
longer exist, they cannot release any locks they may 
have initiated during their operation. 
Therefore, 
unless specific action is taken, these records or 
files remain locked forever. 
What must be done 
after a computer failure of this type is to unlock 
all records which were locked by processes which 
terminated at the time the computer failed. 
This is 
done by truncating the length of the 1I.10k ll files to 
zero, and removing any files that exist in the fisam 
directory. 
(This action circumvents the C-ISAM 
locking system, 
so it should be done only when no 
process is currently using C-ISAM.) 
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VIII. 
Building and Manipulating C-ISAM Files 


This section discusses the creation and manipu- 
lation of C-ISAM files through C language examples. 
These examples are based on a very simple personnel 
system. 
The goal of the personnel system is to keep 
up-to-date information on employees. 
This informa- 
tion includes the names, addresses, 
job titles, and 
salary histories for all employees. 


The personnel system consists of two C-ISAM 
files, 
the "employee" file, 
and the "performance" 
file. 
The employee file holds personal information 
about each employee. 
Each record holds the employee 
number, name, and address for a single worker. 
The 
performance file holds information pertaining to 
each job performance review an employee has had. 
There is one record for each performance review, 
job 
title change, or salary change an employee has had. 
For every employee record in the personnel file 
there may be many records in the performance file. 
The field definitions for the records in both the 
personnel file and the performance file are shown 
below: 


Employee File Definition 


Field Name 


Employee number 
Last name 
First name 
Address 
City 
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Location in Record 


o - 
3 LONGTYPE 
4 - 23 CHARTYPE 
24 - 43 CHARTYPE 
44 - 63 CHARTYPE 
64 - 83 CHARTYPE 
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, 


•• 
Performance File Definition 


t 


f 


Field Name 


Employee number 
Review date 
Job rating 
Salary after review 
Title after review 


Building A C-ISAM File 


Location in Record 


o - 
3 LONGTYPE 
4 - 
9 CHARTYPE 
10 - 11 
CHARTYPE 
12 
19 DOUBLETYPE 
20 - 50 CHARTYPE 


The following C language example creates both 
the employee and the performance files. 
It is im- 
portant to note that the primary keys must defined 
for every file created. 


#inelude <isam.h> 


#define SUCCESS 0 


struet keydese key; 
int estart, nparts; 
int ee, fdemploy, 
fdperform; 


/* 
This program builds the C-ISAM file systems for the 
data files employees and 
pe~formanee. 


*/ 


main() 
{ 
mkemplkey() ; 
fdemploy = ee = isbuild("employee", 84, &key, 
ISINOUT 
+ ISEXCLLOCK); 
if (ee < SUCCESS) 
{ 
printf("isbuild error 
%d for employee file\n", 
iserrno); 
exit(1); 
} 
iselose(fdemploy); 
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exit(1); 
} 
isclose(fdperform); 


if (cc < SUCCESS) 
{ 
printf( "isbuild error %d for performance file\n", 
iserrno); 


mkperfkey( ) ; 
fdperform = cc = isbuild("perform", 49, &key, 
ISINOUT 
+ ISEXCLLOCK); 


mkemplkey( ) 
{ 
key.k flags = 0; 
key.k-nparts = 0; 
cstart = 0; 
nparts = 0; 


addpart(&key, 4, 
LONGTYPE); 


mkperfkey( ) 
{ 
key.k_flags = COMPRESS; 
key.k nparts = 0; 
cstart = 0; 
nparts = 0; 


addpart(&key, 4, LONGTYPE); 
addpart(&key, 6, CHARTYPE); 


addpart(keyp, len, type) 


register struct keydesc *keyp; 
int len; 
int type; 
{ 
keyp->k part[nparts).kp start = cstart; 
keyp->k-part[nparts).kp-Ieng 
len; 
keyp->k-part[nparts).kp-type = type; 
keyp->k-nparts = ++nparts; 
cstart += len; 
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Adding Secondary Indexes 


Often the indexes defined to be primary indexes 
are not adequate for some applications. 
In the case 
of this application two secondary indexes are 
desirable--an index on "last name" in the employee 
file, 
and an index on the field "salary" in the per- 
formance file. 
The following program creates these 
two indexes. 
It is important to note that while ad- 
ding indexes the file must be opened with an ex- 
clusive lock. 
Exclusive file locks are specified in 
the mode parameter of the isopen call by ini tializ- 
ing that parameter to ISINOUT + ISEXCLLOCK. 
The 
ISINOUT specifies that the file is to be opened for 
both input and output, and the 
ISEXCLLOCK macro ad- 
ded to ISINOUT indicates that the file is to be ex- 
clusively locked for the current process and that no 
other process will be allowed to access this file. 
Note also that duplicates are to be allowed for both 
secondary indexes and that the Iname field is to 
have full compression for its values stored in the 
index file. 
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#include <isam.h> 


#define SUCCESS 0 


struct keydesc key; 
int cstart, nparts; 
int fdemploy, 
fdperform; 


/* This program adds secondary indexes for the last name 
field in the employee file, 
and the salary field in 
the performance fHe. 
*/ 


main( ) 
{ 
int cc; 
fdemploy = cc = isopen("employee", 
ISINOUT 
+ ISEXCLLOCK); 
if (cc < SUCCESS) 
{ 
printf("isopen error Id for employee file\n", 
iserrno) ; 
exit(1); 
} 


mklnamekey() ; 
cc = isaddindex(fdemploy, &key); 
if (cc 
!= SUCCESS) 
{ 
printf("isaddindex error %d for employee lname key\n", 
iserrno) ; 
exit(1); 
} 
isclose(fdemploy); 


fdperform 
= cc 
= isopen( "perform", 
ISINOUT 
+ ISEXCLLOCK); 
if (cc < SUCCESS) 
{ 
printf("isopen error 
%d for performance file\n", 
iserrno) ; 
exit(1); 
} 


mksa lkey ( ) ; 
cc 
= isaddindex(fdemploy, &key); 
if (cc 
!= SUCCESS) 
{ 
printf("isaddindex error 
%d for perform sal key\n", 
iserrno) ; 
exit(1); 
} 
isclose(fdperform) ; 
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mklnamekey( ) 
{ 
key.k flags 
= ISDUPS + COMPRESS; 
key.k-nparts 
= 0; 
cstart = 4; 
nparts 
= 0; 


addpart(&key, 
20, 
CHARTYPE); 


mksalkey( ) 
{ 
key.k flags 
= ISDUPS; 
key.k-nparts 
= 0; 
cstart 
= 12; 
nparts 
= 0; 


addpart(&key, sizeof(double), DOUBLETYPE); 


addpart(keyp, len, type) 


register struct keydesc *keyp; 
int len; 
int type; 
{ 
keyp->k part[nparts].kp start 
= cstart; 
keyp->k-part[nparts].kp-leng = len; 
keyp->k-part[nparts].kp-type 
= type; 
keyp->k-nparts 
= ++nparts; 
cstart += len; 
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Adding Data 


The following program simply adds records to 
the "employee" file by prompting standard input for 
values of the fields in the data record. 
Note that 
the "employee" file is opened with the 
ISOUTPUT flag 
as its mode parameter. 


#include <isam.h> 
#include <stdio.h> 


#define WHOLEKEY 0 
#define SUCCESS 0 
#define TRUE 1 
#define FALSE 0 


char emprec[85]; 
char perfrec[51]; 
char line[82]; 
long empnum; 


struct keydesc key; 
int cstart. nparts; 
int fdemploy, fdperform; 
int finished = FALSE; 


/* This program adds a new employee record to the employee 
file. 
It also adds that employee's first employee 
performance record to the performance file. 
*/ 


maine ) 
{ 
int cc; 
fdemploy = cc = isopen ("employee", 
ISMANULOCK 
+ ISOUTPUT); 
if (cc < SUCCESS) 
{ 
printf("isopen errol' %d for employee file\n", 
iserrno) ; 
exit(1); 
} 
fdperform = cc = isopen("perform", 
ISMANULOCK 
+ ISOUTPUT); 
if (cc < SUCCESS) 
{ 
printf("isopen errol' %d for performance file\n", 
iserrno) ; 
exit(1); 
} 
getemployee() ; 


56 
C-ISAM 


while(!finished) 
{ 
addemployee(); 
getemployee ( ) ; 
} 
isclose(fdemploy); 
isclose(fdperform); 


getperform( ) 
{ 
double new salary; 
if-(empnum == 0) 
{ 
finished = TRUE; 
return(O) ; 
} 
stlong(empnum, perfrec); 


printf("Start Date: "); 
fgets(line, 80, stdin); 
stchar(line, perfrec+4, 6); 


steharC "gn, perfree+10, 1); 


printf("Starting salary: "); 
fgets(line, 80, stdin); 
sseanf(line, "Ilf", anew salary); 
stdbl(new_salary, perfrec+11); 


printf(nTitle 
: "); 
fgets(line, 80, stdin); 
stehar(line, perfree+19, 30); 


printf("\n\n\n"); 


addemployee ( ) 
{ 
int ee; 
ee = iswrite(fdemploy, empree); 
if (ee 
!= SUCCESS) 
{ 
printf("iswrite error Id for employee\n", iserrno); 
iselose(fdemploy); 
exit( 1); 
} 
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addperform( ) 
{ 
int cc; 


isclose(fdperform) ; 
exit(1); 
} 


while (n--) putchar(*(c++»; 


cc = iswrite(fdperform, 
if (cc 
!= SUCCESS) 
{ 
printf( "iswrite 


putnc(c,n) 
char *c; 
int n; 
{ 


} 


perfrec); 


error %d for performance\n", 
iserrno) ; 


1etemPlOyee( ) 


printf("Employee number (enter ° to exit): It); 
fgets(line. 80, stdin); 
sscanf(line, "%ld". &empnum); 
if (empnum == 0) 
( 
finished = TRUE; 
return(O) ; 
} 
stlong(empnum. emprec); 


printf("Last name: 
It); 
fgets(line. 80, stdin); 
stchar(line, emprec+4, 20); 


printf("First name: 
It); 
fgets(line. 80, stdin); 
stchar(line, emprec+24, 20); 


printf("Address: It); 
fgets( line, 80, stdin); 
stchar(line, emprec+44. 20); 


printf("City: It); 
fgets(line. 80, stdin); 
stchar(line, emprec+64, 20); 


getper form( ) ; 
addperform() ; 
printf("\n\n\n"); 
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*dest++ = *src++; 


while (i++ <= num) 
*dest++ = 
t 
'; 


stchar(src, dest, num) 
/* move 
NUM sequential characters from SRC to DEST */ 


char *src; 
char *dest; 
int num; 
{ 
int i; 


for (i = 1; i 
<= num && *src != '\n' 
&& src != 0; 
i++) 
/* don't move carriage */ 
/* returns or nulls 
*/ 
/* pad remaining characters in blanks */ 


Sequential Access 


The next C language example shows how to read a 
file sequentially. 
In this particular case the "em- 
ployee" file is being read in order of the primary 
key "employee number". 
Since the "employee number" 
index is defined as ascending with no duplicate key 
values allowed, the sequence of records will print 
from the lowest value of employee number to the 
highest value of employee number. 
This will contin- 
ue until the isread call using ISNEXT returns the 
value EENDFILE, which indicates that the end of file 
has been reached. 
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#include <isam.h> 


#define WHOLEKEY 0 
#define SUCCESS 0 
#define TRUE 1 
#define FALSE 0 


char emprec[85]; 


struct keydesc key; 
int cstart, nparts; 
int fdemploy, fdperform; 
int eof = FALSE; 


/* This 
~rogram sequentially reads through the employee 
file by employee number, printing each record to 
stdout as it goes. 
*/ 


maine ) 
{ 
int cc; 
fdemploy = cc = isopen("employee", 
ISINPUT+ISAUTOLOCK); 
if (cc < SUCCESS) 
{ 
printf("isopen error Id for employee file\n", 


iserrno); 
exit(1) ; 
} 
mkemplkey( ); 
cc = isstart(fdemploy, &key, 
WHOLEKEY, emprec, 
ISFIRST); 
if (cc 
!= SUCCESS) 
{ 
printf("isstart error Id\n", iserrno); 
isclose(fdemploy); 
exit( 1) ; 
} 
. 


getfirst() ; 
while 
(! eof) 
{ 
showemployee() ; 
getnext() ; 
} 
isclose(fdemploy); 
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while (n--) putchar(*(c++»; 


showemployee() 
{ 
printf("EmpIoyee number: lId", 
printf("\nLast name: "); 
printf("\nFirst name: "); 
printf("\nAddress: "); 
printf("\nCity: "); 
printf("\n\n\n"); 


putnc(c, n) 
char *c; 
int n; 
{ 


} 


IdIong(emprec»; 
putnc(emprec+4, 20); 
putnc(emprec+24, 20) 
putnc(emprec+44, 20) 
putnc(emprec+64, 20) 


eof = TRUE; 
break; 


getfirst( ) 
{ 
int cc; if (cc = isread(fdempIoy, 
{ 
switch(iserrno) 
{ 
case EENDFILE 


emprec, ISFIRST» 


defaul t 
{ 
printf("isread ISFIRST error Id \n", 
iserrno) ; 
eof = TRUE; 
retum( 1); 
} 


} 
return(O) ; 
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getnext( ) 
{ 
int ee; if (ee 
= isread(fdemploy, empree, 
ISNEXT» 
{ 
switeh(iserrno) 
{ 
case EENDFILE 
eof 
= TRUE; 
break; 
defaul t 
( 
printf("isread ISNEXT error Id \n", 
iserrno) ; 
eof = TRUE; 
return(1); 
} 


} 
return(O) ; 


mkemplkey( ) 
{ 
key.k flags 
= 0; 
key.k-nparts = 0; 
estart 
= 0; 
nparts = 0; 


addpart(&key, 4, 
LONGTYPE); 


addpart(keyp, len, type) 
register struet keydese *keyp; 
int len; 
int type; 
{ 
keyp->k part[nparts].kp start = estart; 
keyp->k-part[nparts].kp-leng = len; 
keyp->k-part[nparts].kp-type = type; 
keyp->k-nparts = ++nparts; 
estart += len; 
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Random Access 


The following program describes how random ac- 
cess to a C-ISAM file can be accomplished. 
This 
program interactively retrieves an employee number 
from standard input, searches for it in the employee 
file, 
and prints the results of its search to stan- 
dard output. 
Note that the ISEQUAL macro is used to 
specify the read mode to isread in the C function 
called reademp. 
If no record which corresponds to 
the value entered by the user is found for employee 
number a condition code of ENOREC is returned by 
isread. 
It is the responsibility of the C program- 
mer to handle that return code in an appropriate 
manner. 
If ENOREC is returned the record buffer 
sent as the record parameter to the isread call will 
not have been changed (i.e. no record will have been 
read). 


#include <isam.h> 
#include <stdio.h> 


#define WHOLEKEY 0 
#define SUCCESS 0 
#define TRUE 1 
#define FALSE 0 


char emprec[83]; 
char line[80]; 
long empnum; 


struct keydesc key; 
int cstart, nparts; 
int fdemploy, 
fdperform; 
int eof = FALSE; 


/* 
This program interactively retrieves an employee's employee 
number from stdin, 
searches for it in the employee file, 
and prints the employee record that has that value as its 
employee number field. 
*/ 
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main( ) 
{ 
int cc; 
fdemploy • cc • isopen("employee", 
ISINPUT+ISAUTOLOCK); 
if (cc < SUCCESS) 
{ 
printf("isopen error 
%d for employee file\n", 
iserrno); 
exit(1); 
} 
mkemplkey() ; 
getempnum() ; 
while 
(empnum !. 0) 
{if (reademp() 
getempnum( ) ; 
} 
isclose(fdemploy); 


SUCCESS) showemployee(); 


Tetempnum( ) 


printf("Enter the employee number (0 to quit): "); 
fgets(line, 80, stdin); 
sscanf(line, "%ld", &empnum); 
stlong(empnum, emprec); 


while (n--) putchar(*(c++»; 


showemployee( ) 
{ 
printf("Employee number: %ld", 
printf("\nLast name: "); 
printf("\nFirst name: "); 
printf("\nAddress: "); 
printf("\nCity: "); 
printf("\n\n\n"); 


putndc, n) 
char *c; 
int n; 
{ 


} 
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ldlong(emprec»; 
putnc(emprec+4, 20); 
putnc(emprec+24, 20) 
putnc(emprec+44, 20) 
putnc(emprec+64, 20) 
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reademp() 
{ 
int cc; 
cc 
= isread(fdemploy, emprec, 
ISEQUAL); 
if (cc 
!= SUCCESS) 
{ 
switch (iserrno) 
{ 
case EENDFILE 
eof = TRUE; 
break; 
default: 
( 
printf("isread ISEQUAL error Id\n", 
iserrno) ; 


eof 
= TRUE; 
return( 1); 
} 


} 
return(O) ; 


yetfirst( ) 


int cc; if (cc 
= isread(fdemploy, emprec, ISFIRST)) 
{ 
swi tch( iserrno) 
{ 
case EENDFILE 
eof = TRUE; 
break; 
default 
{ 
printf("isread ISFIRST error Id \n", 
iserrno); 
eof 
= TRUE; 
return( 1); 
} 


} 
return(O) ; 
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getnext( ) 
{ 
int ee; if (ee = isread(fdemploy, empree, 
ISNEXT)) 
{ 
swi teh( iserrno) 
{ 
case EENDFILE 
eof = TRUE; 
break; 
defaul t 
{ 
printf("isread ISNEXT error %d \n", 
iserrno); 
eof = TRUE; 
return( 1); 
} 


} 
return(O) ; 


mkemplkey( ) 
{ 
key.k flags = 0; 
key.k-nparts 
= 0; 
estart 
= 0; 
nparts = 0; 


addpart(&key, 4, 
LONGTYPE); 


addpart(keyp, len, type) 


register struet keydese *keyp; 
int len; 
int type; 
{ 
keyp->k part[nparts].kp start = estart; 
keyp->k-part[nparts].kp-leng 
len; 
keyp->k-part[nparts].kp-type = type; 
keyp->k-nparts = ++nparts; 
estart += len; 
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Chaining 


The following example shows how to chain to a 
record which is the last record in a chain of asso- 
ciated records. 
Here is an illustration of how the 
performance records appear logically by the primary 
key. 
The primary index is a composite index made up 
of the employee number and review date. 


Emp. no. 
Review date 
Job rating 
New Salary 
New Title 
-------- ----------- ---------- ---------- --------- 


1 
790501 
g 
20,000 
PA 
1 
800106 
g 
23,000 
PA 
1 
800505 
f 
24,725 
PA 
2 
760301 
g 
18,000 
JP 
2 
760904 
g 
20,700 
PA 
2 
770305 
g 
23,805 
PA 
2 
770902 
g 
27,376 
SPA 
3 
800420 
f 
18,000 
JP 
4 
800420 
f 
18,000 
JP 


The following program's function is to add in- 
teractively a new performance file record. 
The 
record will contain the date that the salary review 
took place, the employee's current job rating, the 
employee's new salary (based on rating), and the 
employee's new or current job title. 
All the fields 
except new salary are entered by the user. 
The new 
salary is calculated by looking at the employee's 
most recent salary. 
It can be found at the end of a 
"chain" of associated performance history records 
for that employee. 
By multiplying the employee's 
most recent salary by a factor depending on that 
employee's job rating, the new salary is then calcu- 
lated. 
Note that the finding of the most recent 
performance history record for a given employee is 
accomplished by positioning the record pointer in 
C-ISAM to the record just past the highest possible 
review date for that employee. 
In the example, the 
highest possible date used is 999999. 
By executing 
an isread with the ISPREV option as the mode parame- 
ter, the most recent performance history record for 
that employee is retrieved. 
This technique is con- 
siderably faster than finding the first performance 
history record for a particular employee, and then 
executing ISNEXTs to "chain" through them all. 
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#include <isam.h> 
#include <stdio.h> 


#define WHOLEKEY 0 
#define SUCCESS 0 
#define TRUE 1 
#define FALSE 0 


char perfrec[51]; 
char operfrec[51]; 
char line [81] ; 
long empnum; 
double new_salary, old_salary; 


struct keydesc key; 
int cstart, nparts; 
int fdemploy, 
fdperform; 
int finished 
= FALSE; 


/* This program interactively reads data from stdin and adds 
performance records to the "perform" file. 
Depending on 
the rating given the employee on job performance, the 
following salary increases are placed in the salary field 
of the performance file. 


*/ 


rating 


p (poor) 
f (fair) 
g (good) 


percent increase 


0.0 % 
7.5 % 


13.5 % 


maine ) 
{ 
int cc; 
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fdperform 
= cc 
= isopen( "perform", 
ISINOUT.ISAUTOLOCK); 
if (cc < SUCCESS) 
{ 
printf( "isopen error %d for. performance file\n", 
iserrno); 
exit(1); 
} 
mkperfkey() ; 
getperformance(); 
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else 


(get old salary()) 
-{ - 
finished = TRUE; 
} 


{ 
addperformance(); 
getperformance(); 
} 


while (!finished) 
{if 


} 


isclose(fdperform); 


addo<;!rformance() 
{ 
. 


int cc; 
cc = iswrite(fdperform, perfrec); 
if (cc 
!= SUCCESS) 
{ 
printf("iswrite error %d\n", iserrno); 
isclose(fdperform); 
exit(1); 
} 


getperformance() 
{ 
printf("Employee number (enter ° to exit): "); 
fgets(line, 80, stdin); 
sscanf(line, "%ld", &empnum); 
if (empnum == 0) 
{ 
finished 
= TRUE; 


return(O) ; 
} 
stlong(empnum, perfrec); 


printf("Review Date: "); 
fgets(line, 80, stdin); 
stchar(line, perfrec+4, 6); 


good): "); 
fair, 
g 
printf("Job rating (p = poor, 
f 
fgets(line, 80, stdin); 
stchad line, perfrec+10, 1); 


printf("Salary After Review: "); 
printf("(Sorry, you don't get to add this)\n"); 
new salary = 0.0; 
stdbl(new_salary, perfrec+11); 
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p~intf("Title 
Afte~ Review: "I; 
fgets(line, 
80, stdin); 


steha~(line, 
pe~f~ee+19, 30); 


p~intf("\n\n\n"); 


7et_old_Sala~y() 


int mode, ee; 


byteepy(pe~f~ee, ope~f~ee, 4); 
/* get employee id no. */ 
byteepY("999999", 
ope~f~ee+4, 6); 
/* 
la~gest possible date */ 


ee 
= 
issta~t(fdpe~fo~m, 
&key, 
WHOLEKEY, 
ope~f~ee, 
ISGTEQ); 
if (ee 
!= SUCCESS) 
{ 
switeh( i se~~no) 


{ 
case ENOREC: 
case EENDFILE: 
mode = ISLAST; 


b~eak; 


default: 


p~intf("issta~t e~~o~ 
~d ", 


iserrno) ; 


~etu~n( 1); 


e~~o~ %d in get old 
sala~y\n", 


- 
- 
ise~~no); 


ope~f~ee, 
mode); 


~etu~n(1); 
} 


~etu~n (1); 
} 
if 
(empnbytes(pe~f~ee, ope~f~ee, 4» 
{ 


p~intf("No 
pe~formanee 
~eeo~d 
fo~ employee 
numbe~ 
~ld.\n", 


ldlong(ope~f~ee»; 


} 


{ 
mode 
= ISPREV; 
} 
ee 
is~ead(fdpe~fo~m, 
if (ee 
!= SUCCESS) 
{ 


p~intf("is~ead 


else 
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} 
stdbl(new salary, perfrec+11); 
printf( "Old salary was %f\n", old salary); 
printf( "New salary is %f\n", new_salary); 
} 


else 
I 
printf( "\nPerformance record found. \n\n"); 
old salary = new salary = Iddbl(operfrec+11); 
printf( "Rating: ;;); 
switch(*(perfrec+10)) 
{ 
case 
'pI: 
printf("poor\n"); 
break; 
case 'f': 
printf("fair\n"); 
new salary *= 1.075; 
break; 
case 'g': 
printf("good\n"); 
new salary *= 1.15; 
break; 


bytecpy(src,dest,n) 
register char *src; 
register char *dest; 
register int n; 
{ 
while (n-- > 0) 
{ 
*dest++ = *src++; 
} 


cmpnbytes(byte1, byte2, n) 
register char *byte1, *byte2; 
register int n; 
{ 


if (n <= 0) return(O); 
while (*byte1 
== *byte2) 
{ 
if (--n == 0) return(O); 
++byte1; 
++byte2 ; 
} 
return«(*byte1 & BYTEMASK) 
< (*byte2 & BYTEMASK)) 
? -1 
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mkperfkey( ) 
{ 
key.k flags = COMPRESS; 
key.k-nparts 
= 0; 


cstart = 0; 
nparts = 0; 


addpart(&key, 
4, 
LONGTYPE); 
addpart(&key, 6, CHARTYPE); 


stchar(src, dest, num) 
/* move 
NUM sequential characters from SRC to DEST */ 


char *src; 
char *dest; 
int num; 
{ 
int i; 


for (i = 1; i 
<= num && 


*dest++ 
= *src++; 


while fi++ <= num) 
*dest++ 
= 
' 
'; 


*src 
!= '\n' 
&& src 
!= 0; i++) 
/* don't move carriage 
/* returns or nulls 
/* pad remaining characters in 


*/ 
*/ 
blanks */ 


addpart(keyp, len, type) 


register struct keydesc *keyp; 
int len; 
int type; 
{ 
keyp->k part[nparts].kp start 
= cstart; 
keyp->k-part[nparts].kp-leng 
len; 
keyp->k-part[nparts].kp-type 
= type; 
keyp->k-nparts = ++nparts; 
cstart += len; 
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IX. 
BCHECK 


BCHECK is a utility program that checks and 
repairs index files. 
It compares an index (.idx) 
file to a data (.dat) file to see whether the two 
are consistent. 
If they are not, it asks you wheth- 
er to delete and to rebuild the corrupted indexes. 


In the example below, 
BCHECK is run on the 
customers file. 


% bcheck customers 


BCHECK 
C-ISAM B-tree Checker version 1.04 
Copyright (C) 1982, 1983 Relational Database Systems, 
Inc. 
Software Serial Number RDS-R000001 


C-ISAM File: customers 


Checking dictionary and file sizes. 
Checking data file records. 
Checking indexes and key descriptions. 
Index 1 = unique key 
(0,4,2) 
1 index node(s) used -- 1 index b-tree level(s) used 
Index 2 = unique key 
(4,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 
Index 3 = duplicates 
(19,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 
Index 4 = duplicates 
(34,8,3) 
1 index node(s) used -- 1 index b-tree level(s) used 
Checking data record and index node free lists. 
6 index node(s) used, 
0 free -- 6 data record(s) used, 
0 free 


In this example, 
BCHECK found no errors. 
(Note 
that for each index, 
BCHECK prints a group of 
numbers. 
There may be up to eight groups of numbers 
for each index. 
These numbers indicate the position 
of the key in each record.) 


SCHECK can also be used with any of the follow- 
ing options: 


-i 
check index file only 
-1 
list entries in b-trees 
-n 
answer no to all questions 
-y 
answer yes to all questions 


The syntax for using these options is 
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% bcheck [-ilny] 
cisamfiles 


Unless you use the -n or -y option, 
BCHECK is 
interactive and waits for you to respond to each er- 
ror it finds. 
Use the -y option with caution. 
BCHECK should not be run using the -y option if it 
is the first time you are checking the files. 


Here is a sample run in which BCHECK finds some 
errors. 
The -n option means that each question 
BCHECK asks is automatically answered "no." 
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% bcheck -n customers 


BCHECK 
C-ISAM B-tree Checker version 1.04 
Copyright (C) 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-R000001 


C-ISAM File: customers 


Checking dictionary and file sizes. 
Checking data file records. 
Checking indexes and key descriptions. 
Index 1 = unique key 
(0,4,2) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? no 


Index 2 = unique key 
(4,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? no 


Index 3 = duplicates 
(19,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? no 


Index 4 = duplicates 
(34,8,3) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? no 


Checking data record and index node free lists. 
ERROR: 
3 missing data record(s) Fix data record 
free list 
? no 


6 index node(s) used, 0 free -- 6 data record(s) used, 
0 free 


In this case, the corrupted indexes must be 
deleted and rebuilt. 
Use the -y option to answer 
yes to all questions asked by SCHECK as follows: 
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%bcheck -y customers 


BCHECK 
C-ISAM B-tree Checker version 1.04 
Copyright (C) 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-R000001 


C-ISAM File: customers 


Checking dictionary and file sizes. 
Checking data file records. 
Checking indexes and key descriptions. 
Index 1 = unique key 
(0,4,2) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? yes 


Index 
2 = unique key 
(4,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? yes 


Index 3 = duplicates 
(19,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? yes 


Index 4 = duplicates 
(34,8,3) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 
3 bad data record(s) Delete index 
? yes 


Checking data record and index node free lists. 
ERROR: 
3 missing data record(s) Fix data record 
free list 
? yes 


Recreate data record free list 
Recreate index 4 
Recreate index 3 
Recreate index 2 
Recreate index 1 


3 index node(s) used, 0 free -- 3 data record(s) used, 0 free 
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x. 
The Header File isam.h 


Following is the header file, 
isam.h. 
The file 
contains "defines" that are used for the mode argu- 
ments and also definitions of structures that are 
used in the calls: 


#define CHARTYPE 
#define CHARSIZE 


#define INTTYPE 
#define INTSIZE 


#define LONGTYPE 
#define LONGSIZE 


#define DOUBLETYPE 
#define DOUBLESIZE 


#define FLOATTYPE 
#define FLOATSIZE 


#define UTYPEMASK 
#define USERCOLL(x) 


#define COLLATE1 
#define COLLATE2 
#define COLLATE3 
#define COLLATE4 
#define COLLATE5 
#define COLLATE6 
#define COLLATE7 


#define MAXTYPE 
#define ISDESC 
#define TYPEMASK 


#define BYTEMASK 
#define BYTESHFT 


#define ldint(p) 
#define stint(i,p) 
long ldlong(); 


#ifndef NOFLOAT 
float ldfloat(); 
double lddbl(); 
#endif 
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o 
1 


1 
2 


2 
4 


3sizeof(double) 


4sizeof (floa t) 


OxFFOF 
«x) & UTYPEMASK) 


Ox10 
Ox20 
Ox30 
Ox40 
Ox50 
Ox60 
Ox70 


5 
0200 
1* add to make descending type*1 
017 
1* type mask 
*1 


OxFF 
1* mask for one byte 
*1 
8 
1* shift for one byte 
*1 


«short)«(p)[O]«BYTESHFT)+«p)[1]&BYTEMASK») 
«p)[O]=(i»>BYTESHFT,(p)[1]=(i» 


77 


#define ISFIRST 
0 
1* position to 
fi~st 
~eco~d*1 


#define ISLAST 
1 
1* position to last 
~eco~d*1 


#define ISNEXT 
2 
1* position to next 
~eco~d*1 


#define ISPREV 
3 
1* position to 
p~evious 
~eco~d*1 


#define ISCURR 
4 
1* position to 
cu~~ent 
~eco~d*1 


#define ISEQUAL 
5 
1* position to equal val ue*1 
#define ISGREAT 
6 
1* position to 
g~eate~ value*1 


#define ISGTEQ 
7 
1* position to >= value *1 


1* 
is~ead lock modes *1 
#define ISLOCK 
Ox100 
1* lock 
~eco~d 
befo~e 
~eading*1 


1* isopen, isbuild 
#define ISAUTOLOCK 
#define ISMANULOCK 
#define ISEXCLLOCK 


#define ISINPUT 
#define ISCUTPUT 
#de fine IS INOUT 


lock modes *1 


Ox200 
Ox400 
Ox800 
o 
1 
2 


1* automatic 
~eco~d lock*1 
1* manual 
~eco~d lock 
*1 


1* exclusive isam file lock*1 


1* open 
fo~ input only 
*1 
1* open 
fo~ output only *1 
1* open 
fo~ input and output*1 


1* max 
numbe~ of bytes in key*1 


1* maximum 
numbe~ of key 
pa~ts*1 


1* audit 
t~ail mode 
#define AUDSETNAME 
#define AUDGETNAME 
#define AUDSTART 
#define AUDSTOP 
#define AUDINFO 


#define MAXKEYSIZE 
#define NPARTS 


pa~amete~s 
o 
1 
2 
3 
4 


120 
8 


*1 
1* 
1* 
1* 
1* 
1* 


set new audit 
t~ail name*1 
get audit 
t~ail name *1 


sta~t audit 
t~ail 
*1 
stop audit 
t~ail 
*1 
audit 
t~ail 
~unning ?*I 


st~uct 
keypa~t 


{ 


sho~t kp 
sta~t; 
sho~t kp-leng; 


sho~t kp::type; 
}; 


1* 
sta~ting byte of key 
pa~t*1 
1* length in bytes 
*1 


1* type of key 
pa~t 
*1 


1* flags 
*1 
1* 
numbe~ of 
pa~ts in key*1 


1* each key 
pa~t 
*1 


following is 
fo~ 
inte~nal use only*1 
1* length of whole key 
*1 


1* 
pointe~ to 
~ootnode 
*1 


st~uct keydesc 
{ 


sho~t k flags; 
sho~t 
k-npa~ts; 
st~uct keypa~t 


k 
pa~t[NPARTS]; 
- 
1* the 


sho~t k len; 
long k rootnode; 
}; 
- 
#define k 
sta~t 
k 
pa~t[O].kp 
sta~t 


#define k-Ieng 
k-pa~t[O].kp-leng 


#define k::type 
k::pa~t[O].kP::type 
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#define ISNODUPS 
000 
/* no duplicates allowed*/ 
#define ISDUPS 
001 
/* duplicates allowed*/ 
#define DCOMPRESS 
002 
/* duplicate compression*/ 
#define LCOMPRESS 
004 
/* leading compression*/ 
#define TCOMPRESS 
010 
/* trailing compression*/ 
#define COMPRESS 
016 
/* all compression*/ 


struct dictinfo 
{ 
short di nkeys; 
/* number of keys defined*/ 
short di-recsize 
/* data record size 
*/ 
short di-idxsize 
/* index record size 
*/ 
long di nrecords 
/* number of records in file*/ 
}; 
- 


#define EDUPL 
100 
/* duplicate record*/ 
#define ENOTOPEN 
101 
/* file not open*/ 
#define EBADARG 
102 
/* illegal argument*/ 
#define EBADKEY 
103 
/* illegal key desc*/ 
#define ETOOMANY 
104 
/* too many files open*/ 
#define EBADFILE 
105 
/* bad isam file format*/ 
#define ENOTEXCL 
106 
/* non-exclusive access*/ 
#define ELOCKED 
107 
/* record locked*/ 
#define EKEXISTS 
108 
/* key alrea9Y exists*/ 
#define EPRIMKEY 
109 
/* is primary key*/ 
#define EENDFILE 
110 
/* end/begin of file*/ 
#define ENOREC 
111 
/* no record found*/ 
#define ENOCURR 
112 
/* no current record*/ 
#define EFLOCKED 
113 
/* file locked 
*/ 
#define EFNAME 
114 
/* file name too long*/ 
#define ENOLOK 
115 
/* can't create lock file */ 
#define EBADMEM 
116 
/* can't alloc memory*/ 
#define EBADCOLL 
117 
/* bad custom collating*/ 
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*** 
*/ 


/* 
* For system call errors 
iserrno 
errno (system error code 1-99) 
iserrio 
= 10 call 
+ 10 file 


10 call 
-what system call 
IO:file 
= which file caused error 


#define 10 OPEN 
Ox10 
/* open( ) 
*/ 
Ide fine IO-CREA 
Ox20 
/* creat( ) 
*/ 
#define IO-SEEK 
Ox30 
/* lseek( ) 
*/ 
#define IO-READ 
Ox40 
/* read( ) 
*/ 
#define IO-WRIT 
Ox50 
/* write() 
*/ 
#define IO-LOCK 
Ox60 
/* locking() 
*/ 
#define IO:IOCTL 
Ox70 
/* ioct! () 
*/ 


#define 10 lOX 
Ox01 
/* index file 
*/ 
#define IO:DAT 
Ox02 
/* data file 
*/ 


#defin<! 
T~ 
.~. '.':.'1 
')x03 
/* audit file 
*/ 
#define IO-LOK 
Ox04 
/* lock file 
*/ 
#define IO:SEM 
Ox05 
/* semaphore file */ 


extern int ise rrno; 
/* isam error return code*/ 


extern int iserrio; 
/* system call error code*/ 
extern long isrecnum; 
/* recprd number of last call*/ 


extern char isstat1; 
/* cobol status characters*/ 
extern char isstat2 ; 
extern char *isversnumber; 
/* C-ISAM version number*/ 


extern char *isccpyright; 
/* RDS copyr ight 
*/ 
extern char *isserial; 
/* C-ISAM software serial number */ 
extern int 
issingleuser; 
/* set for single user access*/ 


extern int 
is nerr; 
/* highest C-ISAM error code*/ 
extern char *is_errlist[] ; 
/* C-ISAM error messages*/ 


/* 
* 
*/ 


error message usage: 
if (iserrno >= 100 && iserrno < is nerr) 


printf("ISAM error %d: %\n", isserrno, is_errlist[iserrno-100]); 


/* num of bytes in audit header*/ 


struct audhead 
{ 
char au type[1]; 
char au-time [4] ; 
char au-procid[2]; 
char au:userid[2]; 
}; 
#define AUDHEADSIZE 
9 


/* audit record type 
/* audit date-time 
/* process id number 
/* user id number 


A,D,R,W*/ 
*/ 
*/ 
*/ 
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XI. 
Status Bytes and iserrno 


When a C-ISAM error occurrs, iserrno can assume 
values ranging from 1 to 113. 
UNIX errors range 
from 1 - 99 and C-ISAM errors range from 100 - 113. 
The C-ISAM error codes indicate the following: 


Macro 


EDUPL 


Number 


100 


Text 


An attempt was made to add a 
duplicate value to an index via 
iswrite, isrewrite, isrewcurr or 
isaddindex. 


Status 
Status 
Byte 1 
Byte 2 


2 
2 


ENOTOPEN 101 
An attempt was made to perform 
some operation on a C-ISAM file 
that was not previously opened 
using the isopen call. 
9 
o 


9 


EBADARG 
102 


EBADKEY 
103 


One of the arguments of the C-ISAM 
call is not within the range of 
acceptable values for that argument. 
9 


One or more of the elements that 
make up the key description is 
outside of the range of acceptable 
values for that element. 


o 


o 


ETOOMANY 104 
The maximum number of files that 
may be open at one time would be 
exceeded if this request were 
processed. 
9 
o 


EBADFILE 105 


ENOTEXCL 106 


The format of the C-ISAM file has 
been corrupted. 
9 


In order to add or delete an index, 
the file must have been opened with 
exclusive access. 
9 


o 


o 


ELOCKED 
107 


EKEXISTS 108 
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The record or file requested by 
this call cannot be accessed 
because it has been locked by 
another user. 


An attempt was made to add an 
index that has been defined 
previously. 


9 


9 


o 


o 
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EPRIMKEY 109 


EENDFILE 110 


ENOREC 
111 


ENOCURR 
112 


EFLOCKED 113 


EFNAME 
114 


ENOLOK 
115 


EBADMEM 
116 


EBADCOLL 117 


An 
~ttempt 
was made to delete 
the primary key value. 
The 


primary key may not be deleted 
by the isdelindex call. 


The beginning or end of file was 
reached. 


No record could be found that 
contained the requested value in 
the specified position. 


This call must operate on the cur- 
rent record. 
One has not been de- 
fined. 


The file is exclusively locked by 


another user. 


The file name is too long. 


The lock file cannot be created. 


Adequate memory cannot be 
allocated. 


Bad custom collating 


9 


2 


2 


9 


9 


9 


9 


9 


o 


o 


3 


o 
o 
o 


o 
o 


Two bytes will be used to hold status informa- 
tion after C-ISAM calls. 
They are related in the 
following way. 
The first byte will hold status in- 
formation of a general nature, 
such as success or 
failure of a C-ISAM call. 
The second byte will con- 
tain more specific information that has meaning 
based on the status code in byte one. 
The values of 
the status bytes will be: 


Byte One 
o - Successful Completion 
1 - 
End of File 
2 - Invalid Key 
3 - System Error 
9 - User Defined Errors 
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When status key 
one is: 
Status key two indicates: 


0-9 
a 


2 


9 
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a - No further information is available 


2 - Duplicate key indicator 


- after a READ this indicates that the 
key value for the current key is 
equal to the value of that same key 
in the next record. 


- After a WRITE or REWRITE this indicates 
that the record just written created a 
duplicate key value for at least one 
alternate record key for which 
duplicates are allowed. 


1 - The primary key value has been changed 
by the 
COBOL program between the 
successful execution of a READ 
statement and the execution of the 
next REWRITE statement. 


2 - 
An attempt has been made to write or 
rewrite a record that would create a 
duplicate key in an indexed file. 


3 
~. No record with the specified key can 
be found. 


4 - An attempt has been made to write 
beyond the externally defined 
boundaries of an indexed file. 


The value of status key two is defined 
by the user. 
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XII. 
File Formats 


DICTIONARY FORMAT 


Byte 
Offsets 
o 
2 bytes - va11dation 
: 
value 
= FE53 : 


2 
l-----------------------------------------------------------------1 
: 
1 byte 
- number of reserved bytes at start of 
: 
: 
index record 
val ue 
= 2 
: 
3 
1-----------------------------------------------------------------l 
: 
1 byte 
- number of reserved bytes at end of 
: 


: 
index record 
val ue 
= 2 
: 
4 
l-----------------------------------------------------------------1 
: 
1 byte 
- number of reserved bytes per key entry 
: 
: 
includes record number) 
value = 4 
: 
5 
l-----------------------------------------------------------------1 
: 
1 byte 
- pointer type and length indicator 
: 
I 
value 
= 4 
I 
6 
1-----------------------------------------------------------------1 
: 
2 bytes - index file record length (excludes relative 
: 
: 
file flag bytes) 
value 
= 511 
: 
8 
1-----------------------------------------------------------------1 
: 
2 bytes - number of keys 
: 


10 
1-----------------------------------------------------------------l 
: 
2 bytes - flags (see explanation of flags, next page) 
: 
1 
value 
= 0 
l 


12 
1-----------------------------------------------------------------l 
: 
1 byte 
- file version number 
: 


13 
l-----------------------------------------------------------------l 
i 
2 bytes - data record length (excludes relative file 
: 


: 
flag bytes) 
: 
15 
l-----------------------------------------------------------------: 
: 
4 bytes - record number of first key information record 
: 
19 1-----------------------------------------------------------------l 
: 
6 bytes - reserved for future use 
: 
25 
l-----------------------------------------------------------------: 
: 
4 bytes - record 
numbe~ of first data free space record 
: 
29 1-----------------------------------------------------------------1 
: 
4 bytes - record number of first index free space record 
: 
33 
l-----------------------------------------------------------------1 
: 
4 bytes - record number of last record on data file 
: 
37 
l-----------------------------------------------------------------l 
: 
4 bytes - record number of last record on index file 
: 


41 
1-----------------------------------------------------------------l 
: 
4 bytes - transaction number 
: 
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45 
1-----------------------------------------------------------------l 
: 
4 bytes - unique id 
: 
49 
1-----------------------------------------------------------------: 
: 
4 bytes - pointer to audit trail information 
: 


KEY DESCRIPTION FORMAT 


Byte 
Offsets 
o 
2 bytes - number of bytes used in this node 


2 
4 bytes - record number of continuation record 


6 
2 bytes - length of description 


8 
------------------------------------------------------- 
4 bytes - address of root node 


12 


13 


15 


17 


---1-b;t~-:-~~;;;~;;~~~-fl;;;--------------------------: 
: 
-------------------------------------------------------\ 
2 bytes - length of key part 1 (top bit 
= dups) 
: 
I 
I 
-------------------------------------------------------l 
2 bytes - position 
: 
I 
I 
-------------------------------------------------------l 
1 byte 
- type 
(0 = alphanumeric) 
:: 


repeats 
for 
each 
part 


! 
~- 


509 
------------------------------------------------------- 
1 byte - flag 
value 
= FF 
510 
------------------------------------------------------- 
1 byte - end of record flag - indicates record type 
high bit is used for security 
value = 7E 


C-ISAM 
85 


B TREE NODE FORMAT 


Byte 
Offsets 
o 
2 bytes - number of bytes used in this node 


2 
------------------------------------------------------- 
1 byte 
- count of leading bytes 


3 
------------------------------------------------------- 
1 byte 
- count of trailing blanks 


4 
------------------------------------------------------- 
N bytes - key 


4+N 
------------------------------------------------------- 
2 bytes - if needed for duplicates 


6+N 
4 bytes - pointer (top' bit may be used as a 
duplicates flag) 


509 
------------------------------------------------------- 
1 byte 
- index tree number (this is always the 
second to the last byte in the node) 
510 
------------------------------------------------------- 
1 byte 
- level in tree (0 • leaf node) (this is 
always the last byte in the node) 
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repeats 
for 
each 
key 
entry 
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FREE LIST FORMAT 


Byte 
Offsets 
o 
2 bytes - number of bytes used in this node 
: 
I 
I 
2 
-------------------------------------------------------1 
4 bytes - record number of continuation record 
1 
I 
I 
6 
-----------------~-------------------------------------l 
N bytes - space for up to 126 record numbers 
1 
I 
I 


.509 
------------------------------------------------------- 
i 
1 byte 
- FF indicates a free list for data file 
: 
FE indicates a free list for index file 
I 
510 
i-------------------------------------------------------I 
: 
1 byte 
- end of record flag - indicates record type 1 


: 
high bit is used for security 
value = 7FI 


AUDIT TRAIL NODE FORMAT 


Byte 
Offsets 
o 
2 bytes - number of bytes used in this node 
1 
I 
I 
I 
2 
:-------------------------------------------------------I 
: 
2 bytes - flags 
0 = audit trail is on 
I 


: 
1 = audit trail is off 
: 
4 
1-------------------------------------------------------I 
1 
64 bytes - audit trail path name 
1 


I 
I 
I 
I 


509 
------------------------------------------------------- 
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1 byte 
- end of record flag - indicates record type 1 


high bit is used for security 
value = 7DI 
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